   _____ _     __     ____  _ ________
  / ___/(_)___/ /__  / __ \(_) __/ __/
  \__ \/ / __  / _ \/ / / / / /_/ /_    v230 (18th July 2004)
 ___/ / / /_/ /  __/ /_/ / / __/ __/        by Miss H. Bazley
/____/_/\__,_/\___/_____/_/_/ /_/     

                                   
PURPOSE OF THE PROGRAM

SideDiff acts as a basic desktop interface to the GNU 'diff' and 'patch'
utilities, allowing you to view  and edit the differences between two text or
BASIC files in the form of a scrolling side-by-side display.   Drag two files
into the program's window (separately or together) to view the differences
between them, or drag an existing output file from GNU 'diff' into the
program. Select sections with the mouse and click on the transfer icon to
copy the selected lines from one file into the other.   (Warning:  this will
alter your original data!)

This application supports interactive help - run !Help and then point at an
icon or menu entry to find out what it does.


HARDWARE/SOFTWARE REQUIREMENTS

This program will run as supplied under all versions of RISC OS from 3 to 5.
It requires the DDEUtils module to pass parameters.


THE DISPLAY

The program will render 'unified' output from GNU diff into two panes in a
desktop window.   The filenames of the two files that were compared are shown
above the relevant display panes, followed by a coloured listing of the
'chunks' of data where differences between the two files were found.

The line numbers of the start and end of each 'chunk', plus any context
header (see below under DIFF OPTIONS), are shown in green.   Text common to
both files is shown in black.   Lines which only appear in the 'old' file are
shown in blue in the lefthand pane;  lines which only appear in the 'new'
file are shown in red in the righthand pane.   Any 'extra' lines necessary to
align the two chunks correctly (because large sections have been inserted or
deleted) are occupied by a single grey hyphen '-'.   It should be easy to see
how the two files are related to each other.

(These colours are user-definable - see under DISPLAY OPTIONS)

Between the two filename icons at the top of the window is the transfer icon.
When a section of text is selected, click on this to transfer it from one
file into the other - see under EDITING SELECTIONS.

The sliders above the top of each pane control the width of the line number
display.  Drag them to the right to increase the column width or to the left
to remove the line numbers altogether.   The pane with the cream-coloured
slider currently has the input focus and will respond to keypresses.

CONTROLLING THE WINDOW

Clicking SELECT on the iconbar icon will open the main window (or bring it to
the front).   The width and height of the display may be adjusted by dragging
the resize icon of the main window to scale the display panes or by using the
toggle size icon to increase the window to its maximum extent - in very wide
screen modes you may be able to view the whole width of each file, otherwise
the horizontal scrollbars must be used to view the ends of lines if
necessary. The vertical scrollbars on either pane may be used to scroll up
and down the display;  the main vertical scrollbar simply indicates the
maximum size of the window.

By default, the scrollbars in the two panes are linked together - scrolling
either pane will also scroll the other.   This makes it easy to view
corresponding sections of the two files.   However, this behaviour is
controlled by the "Link scrollbars" entry in the menu, which is normally
ticked.   Deselecting this option will allow the scrollbars to be moved
independently of each other.   In order to align the two displays again,
simply press CTRL-R, or else reselect "Link scrollbars" and resume scrolling
in one pane - the display in the other pane will automatically return to this
position.

Dragging up or down to make a selection will also cause the window to scroll.
The rate of scroll depends on how close the mouse pointer is to the edge of
the window.

Clicking the mouse on either pane will give the window the input focus,
allowing you to control it via the keyboard - the PageUp/Down, Ctrl and arrow
keys, and Home and End keys can be used for scrolling, while Ctrl-L toggles
the scrollbar linking.   Tab switches the input focus between the two panes,
indicated by giving that pane a cream-coloured slider.   With scrollbar
linking disabled, only the one pane at a time can be controlled - with
linking enabled, both panes scroll together.   Ctrl-R will realign the panes
if they have been scrolled apart while unlinked, and Escape will close the
window.

Holding down the SHIFT key while clicking on either pane will attempt to
display a throwback window displaying the text of the line clicked upon.
This can be used as a means of opening the relevant file at that line.

ADJUST-clicking on the close icon of the SideDiff window will open the
directory containing the files currently displayed - or, if they are in two
different directories, that of the file in the pane with the input focus.
ADJUST-clicking while holding down the Shift key will open the parent
directory without closing the window.

Selecting 'Discard data' from the menu will cause SideDiff to discard any
output currently displayed and any data held on the global clipboard (see
below under EDITING SELECTIONS) in order to free up as much memory as
possible.

The size/name of the display font can be altered from the 'Display'
submenu to increase legibility, resizing the window accordingly.   As in
Edit or Draw, the height of a font can also be altered separately once
its base size has been established, making it taller and thinner or shorter
and fatter than its default aspect.   (However, for convenience,
subsequently adjusting the base size from these submenus will reset the
height to match.)

THE TOOLBAR

By default, SideDiff displays a small toolbar to the left of the window.
This contains four arrow icons which can be using to navigate between changed
sections of a long file.   The top and bottom arrows (with the additional
stripe) move between 'chunks';  the two middle arrows move to the next
changed line of text.  You may also use the space/hyphen keys to move between
changed lines, and Ctrl-PageUp/Ctrl-PageDown or Ctrl-Shift-up/down arrow keys
to move between chunks.   The 'Show toolbar' entry on the window menu
controls whether the toolbar is currently visible or not.

DRAGGING FILES TO THE ICONBAR

IF you drag a single file to SideDiff's iconbar icon instead of to its main
window, a small window will open entitled 'Compare files in SideDiff:',
containing two icons.   The top icon will already be filled in for you.
Dragging another file to the lower icon will compare the two files just as
if they had both been dragged to the main window.   This allows you to
control which files to compare without obscuring a large part of the desktop
by reopening the main display.

DISPLAYING MORE OF A FILE

If the lines in the input files are very long, you may not be able to see the
whole line in the window.   (SideDiff will never display more than a maximum
254 characters of a line in any case.)  You can get a wider view by
concealing the line numbers at the start of each line (either by reducing the
column width to zero or by setting line numbers to 'Off' in the Choices
window - see below under DISPLAY OPTIONS), by changing to a larger screen
mode (the window expands automatically to fit the maximum screen width) or by
switching to the landscape format display.   This displays the two panes one
above each other instead of side by side;  however, it cannot be used for
editing.

The 'Use landscape format' option in the Display section of the Choices
window will configure which of the two display modes is to be used, and the
"Landscape format" entry on the window menu may be used to override this on a
temporary basis.

CREATING 'diff' FILES

SideDiff itself simply acts as a front-end to GNU diff.   Dragging a
selection of two files onto its window or iconbar icon will cause it to
attempt to run 'diff' with appropriate parameters, create an input file in
!Scrap, and display the result.   Greater control as to which is considered
to be the 'old' file and which the 'new' can be obtained by dragging the
files separately to the two panes of the window.   An exception is when a
'unified' diff output file is detected;  no matter where or in what
combination this is dragged, it will always take highest priority, and the
window will be redrawn to show its contents.  Every time the transfer icon is
used to edit the files, a fresh 'diff' is carried out and the display is
updated to reflect the new file contents.   If there is no difference between
the files, the user will be informed.

The top entry on the window menu, "Save diff..." allows you to save out the
diff files thus created as a record of the differences between the files.
They can be reloaded into SideDiff at a later stage.   If the original files
used to create a diff no longer exist, the transfer icon will be greyed out
to indicate that they cannot be edited.   However, if the files still exist
but have been altered by hand since the period at which the diff was taken,
the display will not reflect the true state of the files, and editing, while
possible, may be dangerous!   The "Refresh" menu entry below can be used to
force a fresh comparison between the displayed files, updating the display.

The "Save diff" menu entry is greyed out if no diff file is currently held
within SideDiff.


The Choices window allows considerable control over the command-line options
used (see below under DIFF OPTIONS), allowing the user to stipulate what
kinds of differences between the files are considered significant, and which
are to be ignored.

SideDiff contains its own copies of the command-line utilities GNU diff (2.8.
1) and patch (2.5.8) from Darren Salt.   However, it can be customised to use
'external' copies stored elsewhere on your machine, for example if you
already have a central copy used by other applications.   The system
variables SideDiff$bascat, SideDiff$diff and SideDiff$patch are set up in the
!SideDiff. !Run file to control where SideDiff will look for these
utilities - edit the !Run file to change this.


Note that GNU diff does not cope well when comparing files of differing line-
endings (i.e. LF/CR-LF)!


EDITING SELECTIONS

In addition to displaying the differences between two files, SideDiff allows
you to transfer the differing lines from one file into the other, for example
in order to reinstate deleted sections from a backup copy or to import a
subset of changes from the newer file back into the older one.   Note that
SideDiff does not store more than 254 characters from the start of any line -
so if lines longer than this are detected (for instance when comparing
paragraphs in two 'softwrapped' text files) you will be given a warning
message.   In order to avoid writing back this truncated data and corrupting
the original files, the transfer icon will be greyed out to indicate that
editing is disabled.

Otherwise, the lines to be transferred should be selected in the window with
the mouse.   Text can only be transferred in one direction at a time - you
cannot highlight sections from both files at once!   You will see that two
shades of grey are used for the selection (configurable - see under DISPLAY
OPTIONS).   The darker shade indicates lines which will actually be copied;
the lighter shade indicates the surrounding 'context' and header lines.
SideDiff can remove and insert lines as well as altering them:  copying blank
'catch-up' lines (indicated by a single grey hyphen) will cause the
corresponding line[s] in the other file to be deleted, and copying lines from
the other file over a 'catch-up' line will insert them after the preceding
text.

A selection need not be contiguous.   Click or drag with ADJUST to add or
remove lines from the current selection.   Because copying is a slow, disc-
based process (and because 'patch' only keeps the latest backup for a given
file!), if you wish to make changes to several different parts of a file it
is worth selecting them all and running a single transfer operation, instead
of making a number of separate edits.

Selections can also be exported to other applications via the global
clipboard by pressing Ctrl-C or selecting 'Copy to clipboard' from the
Selection submenu.   Pressing Ctrl-Z or selecting 'Clear selection' will
ensure that no lines are selected anywhere in the main window (but will not
affect any data already placed on the clipboard).

When you have selected the lines you want to change, click on the transfer
icon between the filename displays, or select 'Transfer between panes' from
the Selection submenu.   The direction of the arrows in the transfer
icon indicates in which direction the transfer will take place.   SideDiff
will then run a 'patch' operation to insert the requested edits into the
other file, and generate a fresh 'diff' to show the remaining differences.
This is a non- multi-tasking operation and may take a little while.
Control will return to the desktop when it has finished.

Using the transfer icon will change your *original files*, so be careful!
'patch' generates a single automatic back-up when it edits a file - this may
be found in a subdirectory ~bak of the directory in which the original file
was stored.   Subsequent edits will overwrite this in turn.

EDITING BASIC FILES

The situation when editing BASIC files is a little different.   GNU 'diff'
and 'patch' cannot understand tokenised BBC BASIC, so the actual comparison
and editing take place on local text-versions of the original files held
within the !Scrap application.   When you attempt to make a transfer between
the two files, therefore, SideDiff will present you with a savebox which can
be used to save out the patched result to a new location.   The SideDiff
display will continue to be updated to reflect every edit, but the original
files will *not* be changed.   Note that using the 'Refresh' menu option re-
compares the original files!

The files saved out in this mode are set to filetype &FD1, "BASICTxt".   This
is Acorn's official filetype for BASIC saved as text, and they should load
into your editor in BASIC mode and run when double-clicked upon.   Note,
however, that any line-number information is lost, so you will get a "Program
renumbered" message.

To convert BASICTxt files back into tokenised BASIC, either load them into an
editor and save as BASIC, or open a taskwndow and type
   *BASIC
   TEXTLOAD"<filename>"
   SAVE"<filename>"


USE OF THE HOURGLASS

SideDiff uses the hourglass during various operations.   When generating
diffs, both hourglass LEDS are lit.   When patching files, the top LED only
is lit. When analysing a diff file, neither LED is lit, but the percentage
indicator indicates progress through the file.


THE CHOICES WINDOW

Selecting 'Choices...' from the iconbar menu or ADJUST-clicking on the
iconbar icon will open the Choices window, allowing the user to customise
SideDiff's output and display.   The options are divided into two sections,
those affecting the operation of the 'diff' utility itself and those
affecting SideDiff's own display.   Use the radio icons on the right of the
window to toggle between the sections.

Click on 'Save' to store the current options in the window to disc so that
they will be used by default the next time you run the program, on 'Cancel'
to undo any changes you have made in this window, or on 'Set' to accept these
options for the duration of the current session.

DIFF OPTIONS

SideDiff provides a WIMP interface to a number of GNU diff's command-line
options.   These will affect the program's output, and can be set to ignore
certain types of differences between files in order to reduce the number of
'false positives' - changes that are not relevant - which are reported.
Depending on the types of files you are comparing, you will want to alter
these settings.

  Ignore changes in spacing/Ignore all white-space

These two radio icons control how significant SideDiff considers changes in
'white-space' (spaces, tab characters, etc) to be.   You may deselect both by
ADJUST-clicking with the mouse:  in this case, SideDiff will report any lines
which, in one file, contain more spaces than in the other, even if the
difference is not visible to the human eye.

The 'Ignore changes in spacing' option (-b or --ignore-space-change) will
ignore extra spaces at the ends of lines and between words:  for example,
"The malefactors were sent to see therapists.  " would be considered
identical to "The malefactors     were  sent to see therapists."   It does
*not* ignore differences in indentation.

The 'Ignore all white-space' option (-w or --ignore-all-space) will ignore
*all* white-space for comparison purposes, even if one file has gaps between
words where the other has none:  "   The male factors we resent to see
therapists." would be considered identical to "The malefactors were  sent to
see therapists."   However, this is the only option which can be used to
ignore changes in indentation (extra spaces at the start of lines).

  Ignore case

The 'Ignore case' option (-i or --ignore-case) causes lower-case and upper-
case letters to be treated as equivalent.   It treats accented characters
correctly ( is equivalent to ).

  Ignore blank lines

The 'Ignore blank lines' option (-B or --ignore-blank-lines) will ignore any
changes consisting *only* of blank lines in one or the other file.   (If
other differences are found in the same section, the blank lines will be
reported.)

  Expand tabs

The 'Expand tabs' option (-t or --expand-tabs) will convert any tab
characters found in the input into the requisite number of spaces to align to
the next tab stop (tab stops are assumed to be set every 8 columns).  If this
option is not used, any tab characters in the input files will be displayed
as a single space, throwing off the alignment of columns.   However, if this
option is set and SideDiff is used to *edit* a section of text which contains
tab characters, the expanded version (with multiple spaces in place of a
single tab) will be copied back into the original file, which is rarely
desirable!

  Show whole file

The 'show whole file option' causes SideDiff to attempt to display the
entirety of both input files, rather than just those lines which differ.
This option overrides the 'Lines of context' option below, which will hence
be greyed out if 'Show whole file' is selected.

  Lines of context

The 'Lines of context' option allows you to set how many unchanged (black)
lines will be displayed before and after any (coloured) differences.   If
there are many small changes located close together, increasing the number of
lines of context often causes sections of the diff to run together.
Decreasing the number of lines of context may make the display smaller, but
may result in an increased number of sections.   

The optimum value for producing readable diffs of a manageable size is about
3 lines of context, but you can decrease it down to 1 or increase it up to 9
using the up and down 'bump icons' on the right.   Using a context header can
often make it easier to recognise whereabouts in a file the highlighted
sections occur without using an excessively large number of lines of context.

  Context headers

Context headers are the (by default) green lines of text which appear at the
start of every section of differences.  They are designed to indicate where
in the file the differences were found, e.g. "Lines 13 to 17".   Optionally (-
F or --show-function-line), SideDiff can also search for preceding lines of
text matching a certain pattern, for example function definitions, and
display these in the context header as a further guide to the context in
which the changes appear.

If the 'Use context header for BASIC' option (-F^DEF) is selected, it will
attempt to display the name of the last function or procedure definition
encountered, if any, at the top of each chunk when running a diff on BASIC
files, e.g. "Lines 20 to 27 @@ DEF PROCstartup".   This can be helpful in
identifying the context if changes are found deep inside a long procedure.

The 'Use context header for plain text' option applies to all files which are
not tokenised BASIC, e.g. Obey files, PipeDream files and even BASICTxt files
as well as files of type &FFF ("Text").   When this is selected, you have a
choice of two possibilities - 'Match C function' (-p or --show-c-function),
which assumes that the input is indented C source code, or 'Match regexp',
which allows you to specify what type of line to consider as the start of a
section using 'regular expression' syntax.   For non-program files you will
probably want these options switched off.


DISPLAY OPTIONS

  Line numbers

SideDiff displays line numbers at the start of each line of text, indicating
at what line offset in the file it can be found.   (Note:   in the case of
BASIC files these do *not* necessarily correspond to the line numbers defined
by BASIC!)

'Off' causes the line number display to be suppressed altogether, leaving
more space in the window for text.

'Auto width' causes SideDiff to calculate what it thinks is an appropriate
width to display the line numbers.

'Minimum width' allows the user to specify a width for the column (the actual
figures given are in OS units, but they may be treated as arbitrary values
for the purposes of experimentation).   The column will always be at least as
wide as the minimum width setting, although SideDiff will increase the width
further if it encounters line numbers too long to fit.

All settings are applied to both panes in the window, although column widths
can be adjusted individually after the diff has been generated.

  Landscape format

The landscape-format display allows for the display of longer lines at the
expense of easy comparison between the two files.  The panes are displayed
one above each other, there is no transfer icon, and you cannot select text.
This is a 'safe' mode for those who are worried about accidentally altering
their original files!

Note that the setting of this icon will take effect every time you click on
'Save' or 'Set' in the Choices window, whether or not the display choices are
actually in view - so if you have temporarily switched to landscape format
and are altering the diff options, you may find yourself unexpectedly
changing back to the default mode.

  Colours

SideDiff allows you to configure and save the colour settings used to display
diffs.   You may pick from any of the 16 Wimp desktop colours (due to the way
the program works it is not possible to have fully-definable colours).
Click on the relevant coloured icon to open a colour picker window, and
select a colour from the window to allocate it to that icon.

The settings which may be changed are: Background (the window background -
you may need to change this if you wish to use light-coloured text), Section
heading (the summary which appears at the start of each section of
differences found), Unchanged text (lines in common to both files), Old text
(lines which appear only in the left-hand or top pane), New text (lines which
appear only in the right-hand or lower pane), Blank line (the hyphen
character used to indicate a line which only exists in the other file) and
Selection (in two halves - the first shade is used to colour lines which can
be copied between files and the second shade is used to colour the
surrounding non-copiable lines).


FONT OPTIONS

SideDiff allows you to save your preferred font set-up for future use (the
default setting is to use System font).   Three pop-up menus allow you to
select your desired font face and weight (e.g. Corpus.Medium.Oblique), your
desired font size, and optionally to select a different display height from
its width, altering the font's default aspect.   (If the 'Same' option is
selected, the font height will automatically change to match the overall
size chosen;  if you deselect this option, you will be able to edit the
height separately.)   Below, the outline font sample icon allows you to
view the changes as you edit the settings in this window, although they will
not take effect on the main window until you press 'Set' or 'Save'.


SUMMARY OF KEY SHORTCUTS

Up/down arrow - scroll window up/down one line
PageUp/PageDown - scroll window one screenful at a time
Home (or Ctrl-up arrow) - scroll to top of display
Copy/End (or Ctrl-down arrow) - scroll to bottom of display
Left/right arrow - scroll display to left or right
Space bar - scroll down to next changed line
Hyphen - scroll up to previous changed line
Ctrl-PageUp (or Shift-Ctrl-up arrow) - scroll to start of previous chunk
Ctrl-PageDown (or Shift-Ctrl-down arrow) - scroll to start of next chunk

Ctrl-L - link scrollbars (both panes scroll in unison)
Tab - toggle input focus between left and right panes (only effective when
      scrollbars not linked!)
Ctrl-R - realign panes (when scrolled apart)
Escape - close main window
Ctrl-T - reopen floating toolbar at top left of window
Ctrl-Z - clear current selection (if any)
Ctrl-C - copy current selection to global clipboard

F3 - save out current diff file (if any)
F1 - display this help file


CALLING SIDEDIFF FROM YOUR OWN PROGRAM

SideDiff may be invoked by other programs to display the differences between
two files.   In order to pass the filenames on the command-line, call
SideDiff with the -noicon option:   "*Wimptask <SideDiff$Dir> -noicon <file1>
<file2>" The window will then open to display the two files and SideDiff will
quit silently once the window is closed again.

Note that if there are *no* differences between the files in question GNUDiff
will produce no output, and SideDiff will end up displaying a message to this
effect!

If SideDiff is called with the -noicon option and only one filename:
"*Wimptask <SideDiff$Dir> -noicon <file1>", it will assume that this is the
name of a unified diff file and attempt to display its contents accordingly.
This allows SideDiff to be used as a 'plug-in' to other programs which create
diffs and may wish to use it to display an attractive output.

Multiple copies of SideDiff can be run in this manner, since each will use
its own temporary subdirectory in !Scrap to avoid interfering with the
others' scrap files.   However, they all use the same Choices file, access
to which is provided by an extra entry on the main menu if the -noicon
option is detected.


POSSIBLE FUTURE FEATURES

*DONE*: allow saving of output; what format would be sensible?
- allow parsing of 'context' diff format (seems a bit pointless)
*DONE*: implement 'click on display to open original file at correct line
        offset'
*DONE*: allow display of entirety of original files, not just changed
        sections (means loading both files, not just diffs)
*DONE*: display line numbers
*DONE*: allow copying of altered sections from one original file into the
        other
*DONE*:  Support global clipboard
- Remove main scrollbar/link it to pane scroll
*DONE*: Open small two-path dialogue instead of main window when only one
        file dragged in

COPYRIGHT

The 'diff' utilities were supplied by Darren Salt <ds@youmustbejoking.demon.
co. uk> and are released under the GNU General Public License, as is the
Sliding Heap module, which was written by Steven Haslam.   The DrWimp library
is freeware, supported by Ray Favre <rayfavre@argonet.co.uk>;  see the
comments at the head of the library file for more details.

The toolbar window icons are from the DrWimp example application !PanePain.

The SideDiff application is  Harriet Bazley;  it may be distributed freely,
but altered versions should if at all possible be submitted for my approval
at the address below.

DISCLAIMER

Use of SideDiff's editing facility can, and will, irreparably alter your
files!   YOU HAVE BEEN WARNED.   Keep back-up copies - and don't rely on the
automatic back-ups generated by 'patch'.   I, the author, can accept no
liability for any loss or damage caused either by careless use of this
program or by any bugs it may contain.


CONTACTING THE AUTHOR

The author may be contacted at:	43, Wilton Grove
				Wimbledon
				London
				SW19 3QU

or via e-mail at	harriet@bazley.freeuk.com
			chrisbazley@bigfoot.com 